/**
 * 提供队列接口
 * License: BSD
 * Authors: Lucifer (786325481@QQ.com)
 * Copyright: Copyright (C) 2008 Lucifer. All rights reserved.
 */
module system.collections.IQueue;

import system.collections.IEnumerable;
import system.collections.ICollection;

/**
 * 队列接口。
 * Comments: 队列通常（但并非一定）以 FIFO（先进先出）的方式排序各个元素。
 *
 *           每个方法都存在两种形式：
 *           一种抛出异常（操作失败时），
 *           另一种返回一个特殊值（null 或 false，具体取决于操作）。
 *           插入操作的后一种形式是用于专门为有容量限制的 IQueue(T) 实现设计的；
 *           在大多数实现中，插入操作不会失败。
 *
 *           IQueue(T) 接口并未定义阻塞队列的方法，而这在并发编程中很常见。
 *           IBlockingQueue(T) 接口定义了那些等待元素出现或等待队列中有可用空间的方法，这些方法扩展了此接口。
 *
 *           IQueue(T) 实现通常不允许插入 null 元素，尽管某些实现并不禁止插入 null。
 *           即使在允许 null 的实现中，也不应该将 null 插入到 IQueue(T) 中，因为 null 也用作 tryDequeue 方法的一个特殊返回值，表明队列不包含元素。
 */
public interface IQueue(T) : ICollection!(T), IEnumerable!(T)
{
	/**
	 * 入队。
	 */
	bool enqueue(T item);

	/**
	 * 出队。
	 */
	T dequeue();

	/**
	 * 获取但不移除此队列的头。
	 */
	T peek();

	bool tryEnqueue(T item);

	bool tryDequeue(out T item);

	bool tryPeek(out T item);
}
